“你这接口文档，谁能看懂，写的都是啥，能调通才怪呢！浪费我时间”

“你到底会不会看文档啊，调用方式，参数我都给你写了，你也太菜了吧！”

“你...”

看到这，大家可能都知道咋回事了。前后端分离开发就是这样，需要前后端友好的沟通，更需要一个容易理解的接口文档，方便前端人员开发！不然就可能发生上述互喷的情况。

关于什么是接口文档其他答主已经解释得很清楚了，在这里我就不再赘述了。我主要讲讲衡量接口（API）设计好和坏的准则和一些规范。

槽糕的API接口五花八门，但是好的API接口对于用户来说必须满足以下几个点：

• 易学习：有完善的文档及提供尽可能多的示例和可copy and paste的代码，代码应该尽可能地减少多余的“惊喜”部分。换句话说，你写的代码只需要按照项目要求来编写即可，不用其他华丽的装饰。

• 易使用：对于读者来说，代码没有复杂的程序、细节，只要易于读者学习即可。灵活的API允许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被期望的功能都包含在内。

• 难误用：详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。

而对于开发者来说，要求又是不一样的：

• 易阅读：虽然代码的编写只需要进行一次，但是当调试或者修改的时候都需要对代码进行理解阅读。

• 易开发：最小化的接口是使用最少的类和最少的类成员，但能达到相同的效果。这样使得理解、记忆、调试以及改变API更容易。

API规范

可参考跟着Github学习Restful HTTP API 设计

如http://172.16.0.194:8057/api/order/get

定义返回结果数据结构,更直观

1.返回成功

2.返回失败

具体设计原则可以参考一下wangpeng047这位博主的一些观点：如何正确合理的设计一个接口项目

关于优雅的接口怎么设计，可以参考这篇文章：【Java工程师必备素质】你设计的接口，够优雅吗？

我是 BinSTD，国内领先的 Token 化数据 API 交易平台。